Day 23 使用 typedoc 產生 SDK 文件

寫文件雖然很枯燥乏味，但這卻是決定一個專案會不會被外部開發者採用的重要因素之一，所幸網路上有一些工具可以協助我們產生文件，來減少我們幫專案寫文件的麻煩。

因為專案使用 TypeScript 來開發，所以筆者選擇使用 TypeDoc 來自動產生 SDK 的參考文件。

TypeScript 的安裝請直接查看官方網站，在此不多加贅述。

TypeDoc 設定檔

筆者直接將 TypeDoc 寫在 tsconfig.json 內，筆者接下來會介紹一些比較特別的設定值，建議讀者可以搭配原始碼一起閱讀，原始碼網址為 https://github.com/taichunmin/chameleon-ultra.js/blob/master/tsconfig.json

entryPoints

這個設定值是用來填寫預計提供給外部開發者使用的 SDK 進入點，所以筆者把核心的幾個部分一起放在 src/index.ts，然後其他可以單獨被使用的檔案也都分別列在這個設定值內。

groupOrder

由於核心的 ChameleonUltra 提供很多 methods，為了要讓文件把這些 methods 根據功能區分開來，所以特別在文件上面加上了 @group 進行分類，然後在此設定值內指定分類在文件上顯示的順序。

plugin

TypeDoc 的文件上面提供了不少 Plugin，筆者選擇了幾個 Plugin 來使用，詳細可直接查看原始碼。

寫文件的常用語法

TypeScript 預設只接受以下這種寫法的註解：

/** TypeDoc */

/**
 * TypeDoc
 */

@param 函數的參數說明

/**
 * @param a - the first number
 * @param b - the second number
 */
export function sum(a: number, b: number): number;

可以在函數上面加上 @param 來說明參數的用途。

@example 範例

可以在文件上產生程式碼區塊，來示範如何使用這個程式碼的範例。

@returns 回傳值

可以用來說明這個函式的回傳值代表什麼意思。

/**
 * @param a - the first number
 * @param b - the second number
 * @returns The sum of `a` and `b`
 */
export function sum(a: number, b: number): number;

@group 分類

用來將內容分類，增加文件的可讀性，並且可以在 tsconfig.json 內指定分類顯示在文件上的順序。

參考連結

• TypeDoc 官方文件